Node / meshtastic / Meshtastic-Android / files / core / ble / src / commonMain / kotlin / org / meshtastic / core / ble / BleExceptionClassifier.kt

Displaying Raw • Download

T8b949e/*

* Copyright (c) 2026 Meshtastic LLC

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU General Public License as published by

* the Free Software Foundation, either version 3 of the License, or

* (at your option) any later version.

*

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

* GNU General Public License for more details.

*

* You should have received a copy of the GNU General Public License

* along with this program. If not, see <https://www.gnu.org/licenses/>.

*/

Tf0883e@fileTb4b4b4:Te6edf3SuppressTb4b4b4(Ta5d6ff"Ta5d6ffMatchingDeclarationNameTa5d6ff"Tb4b4b4) T8b949e// File groups the classifier function and its result type.

Tff7b72package T7ee787org.meshtastic.core.ble

Tff7b72import T7ee787com.juul.kable.GattRequestRejectedException

Tff7b72import T7ee787com.juul.kable.GattStatusException

Tff7b72import T7ee787com.juul.kable.NotConnectedException

Tff7b72import T7ee787com.juul.kable.UnmetRequirementException

T8b949e/**

* Classification of a BLE-layer exception for the transport layer to act on.

*

* @property isPermanent `true` if the condition cannot resolve without explicit user re-selection of the device.

* Currently always `false` — all known BLE exceptions can resolve without user intervention (BT toggling, permission

* grants, transient GATT errors). Reserved for future use.

* @property gattStatus the platform GATT status code when available (Android-specific).

* @property message a human-readable description of the failure.

*/

Tff7b72data Tff7b72class T56d364BleExceptionInfoTb4b4b4(Tff7b72val Te6edf3isPermanentTb4b4b4: Tffa657BooleanTb4b4b4, Tff7b72val Te6edf3gattStatusTb4b4b4: Tffa657Int? Tff7b72= Tff7b72nullTb4b4b4, Tff7b72val Te6edf3messageTb4b4b4: Tffa657StringTb4b4b4)

T8b949e/**

* Inspects this [Throwable] and returns a [BleExceptionInfo] if it is a known Kable exception, or `null` if it is

* unrelated to the BLE layer.

*

* This keeps Kable type knowledge inside `core:ble` so that `core:network` (and other consumers) can classify BLE

* exceptions without depending on Kable directly.

*/

Tff7b72fun Te6edf3ThrowableTb4b4b4.Td2a8ffclassifyBleExceptionTb4b4b4(Tb4b4b4)Tb4b4b4: Te6edf3BleExceptionInfo? Tff7b72= Tff7b72when Tb4b4b4(Tff7b72thisTb4b4b4) Tb4b4b4{

Tff7b72is Te6edf3GattStatusException Tff7b72-Tff7b72>

Te6edf3BleExceptionInfoTb4b4b4(

Te6edf3isPermanent Tff7b72= Tff7b72falseTb4b4b4,

Te6edf3gattStatus Tff7b72= Te6edf3statusTb4b4b4,

Te6edf3message Tff7b72= Ta5d6ff"Ta5d6ffGATT error (status Tffd700$Te6edf3statusTa5d6ff): Tffd700$Te6edf3messageTa5d6ff"Tb4b4b4,

Tb4b4b4)

Tff7b72is Te6edf3NotConnectedException Tff7b72-Tff7b72> Te6edf3BleExceptionInfoTb4b4b4(Te6edf3isPermanent Tff7b72= Tff7b72falseTb4b4b4, Te6edf3message Tff7b72= Ta5d6ff"Ta5d6ffNot connectedTa5d6ff"Tb4b4b4)

Tff7b72is Te6edf3GattRequestRejectedException Tff7b72-Tff7b72>

Te6edf3BleExceptionInfoTb4b4b4(Te6edf3isPermanent Tff7b72= Tff7b72falseTb4b4b4, Te6edf3message Tff7b72= Ta5d6ff"Ta5d6ffGATT request rejected (busy)Ta5d6ff"Tb4b4b4)

Tff7b72is Te6edf3UnmetRequirementException Tff7b72-Tff7b72>

T8b949e// Bluetooth disabled or runtime permission missing. Both can resolve without re-selecting the

T8b949e// device (user re-enables BT, or grants permission). Surface as transient so the transport keeps

T8b949e// retrying; UI can show a hint based on the message.

Te6edf3BleExceptionInfoTb4b4b4(Te6edf3isPermanent Tff7b72= Tff7b72falseTb4b4b4, Te6edf3message Tff7b72= Te6edf3message Tff7b72?: Ta5d6ff"Ta5d6ffBluetooth LE unavailableTa5d6ff"Tb4b4b4)

Tff7b72else Tff7b72-Tff7b72> Tff7b72null

Tb4b4b4}

T8b949e/**

* GATT status codes that indicate the BLE session is irrecoverably broken.

*

* Used by [isSessionFatalBleException] and shared across the BLE stack so classification stays in one place.

*/

Tf0883e@SuppressTb4b4b4(Ta5d6ff"Ta5d6ffMagicNumberTa5d6ff"Tb4b4b4)

Tff7b72private Tff7b72val Te6edf3FATAL_GATT_STATUSES Tff7b72=

Te6edf3setOfTb4b4b4(

T8b949e// 0x08 — link-layer supervision timeout (peer out of range or asleep)

T79c0ff8Tb4b4b4, T8b949e// GATT_CONN_TIMEOUT

T8b949e// 0x13 — peer-initiated disconnect (firmware reboot, user power-cycle, nRF52 link drop).

T8b949e// The most common Meshtastic disconnect signal; without it fromRadio would spin-retry a dead link.

T79c0ff1T79c0ff9Tb4b4b4, T8b949e// GATT_CONN_TERMINATE_PEER_USER

T8b949e// 0x16 — link manager protocol timeout (radio firmware/hardware hang)

T79c0ff2T79c0ff2Tb4b4b4, T8b949e// GATT_CONN_LMP_TIMEOUT

T8b949e// 0x3E — connection establishment failed (discovered during connect handshake)

T79c0ff6T79c0ff2Tb4b4b4, T8b949e// GATT_CONN_FAIL_ESTABLISH

T8b949e// 0x85 — generic connection failure; commonly fires at runtime against a stale GATT handle

T79c0ff1T79c0ff3T79c0ff3Tb4b4b4, T8b949e// GATT_ERROR

T8b949e// 0x81 — unrecoverable operation failure

T79c0ff1T79c0ff2T79c0ff9Tb4b4b4, T8b949e// GATT_FAILURE

Tb4b4b4)

T8b949e/**

* Returns `true` if this throwable indicates the BLE session is irrecoverably broken and should be torn down

* (triggering reconnection), as opposed to a transient condition that can be retried.

*

* Also checks the cause chain — if a session-fatal exception is wrapped inside another exception (e.g., by coroutine

* machinery or retry logic), it is still detected. Depth-limited to prevent stack overflow on malformed cause chains.

*/

Tff7b72fun Te6edf3ThrowableTb4b4b4.Td2a8ffisSessionFatalBleExceptionTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657Boolean Tff7b72= Te6edf3isSessionFatalBleExceptionInternalTb4b4b4(Te6edf3maxDepth Tff7b72= T79c0ff1T79c0ff0Tb4b4b4)

Tff7b72private Tff7b72fun Te6edf3ThrowableTb4b4b4.Td2a8ffisSessionFatalBleExceptionInternalTb4b4b4(Te6edf3maxDepthTb4b4b4: Tffa657IntTb4b4b4)Tb4b4b4: Tffa657Boolean Tb4b4b4{

Tff7b72if Tb4b4b4(Te6edf3maxDepth Tff7b72<Tff7b72= T79c0ff0Tb4b4b4) Tff7b72return Tff7b72false

Tff7b72return Tff7b72when Tb4b4b4(Tff7b72thisTb4b4b4) Tb4b4b4{

Tff7b72is Te6edf3NotConnectedException Tff7b72-Tff7b72> Tff7b72true

Tff7b72is Te6edf3GattStatusException Tff7b72-Tff7b72>

Te6edf3status Tff7b72in Te6edf3FATAL_GATT_STATUSES Tff7b72|Tff7b72| Te6edf3causeTff7b72?.Te6edf3isSessionFatalBleExceptionInternalTb4b4b4(Te6edf3maxDepth Tff7b72- T79c0ff1Tb4b4b4) Tff7b72?: Tff7b72false

Tff7b72else Tff7b72-Tff7b72> Te6edf3causeTff7b72?.Te6edf3isSessionFatalBleExceptionInternalTb4b4b4(Te6edf3maxDepth Tff7b72- T79c0ff1Tb4b4b4) Tff7b72?: Tff7b72false

Tb4b4b4}

Tb4b4b4}